PR #696 documents a usercron migration issue introduced in v0.8.2: cronjob.toml is now resolved under $HOME/.openab/ instead of $HOME/. Without moving the file, upgraded instances can start the cron scheduler with 0 jobs and only log no cronjobs yet, making scheduled work silently disappear.

Feat

Docs improvement. It adds an upgrade SOP note for relocating cronjob.toml and a smoke-test checklist item to confirm usercron jobs are loaded after upgrade.

Who It Serves

Deployers and agent runtime operators upgrading OpenAB installations, plus maintainers reviewing upgrade safety.

Rewritten Prompt

Update docs/ai-install-upgrade.md to document the v0.8.2 usercron path migration from $HOME/cronjob.toml to $HOME/.openab/cronjob.toml.

Acceptance criteria:

• Add the migration note in the backup or pre-upgrade section.
• Include the exact mv command or equivalent safe relocation guidance.
• Add a post-upgrade smoke-test item confirming usercron jobs are loaded.
• Mention that count=0 or no cronjobs yet after upgrade may indicate the file is still in the old path.
• Keep the SOP concise and operational.

Merge Pitch

This is worth advancing because it prevents a real upgrade footgun: scheduled jobs can stop running without an obvious failure. The risk is low because the PR is documentation-only and scoped to the upgrade SOP. The likely reviewer concern is whether docs are sufficient, or whether the runtime should also emit a warning or support backward-compatible migration.

Best-Practice Comparison

OpenClaw principles that fit:

• Durable job persistence is relevant because cronjob.toml is persisted scheduler state and must survive upgrades.
• Run logs and warnings are relevant because no cronjobs yet does not clearly identify a path migration problem.
• Gateway-owned scheduling is conceptually related, but this PR only documents operator procedure rather than changing scheduler ownership.
• Isolated executions, explicit delivery routing, and retry/backoff are not directly implicated.

Hermes Agent principles that fit:

• Gateway daemon tick model is relevant only insofar as scheduled jobs must be reliably discovered at daemon startup.
• Atomic writes for persisted state are adjacent but not addressed by this docs PR.
• Fresh session per scheduled run and self-contained prompts are not directly relevant.
• File locking to prevent overlap is unrelated to the migration note.

The PR aligns with the operational spirit of both systems by making scheduler state migration explicit, but it does not add runtime guarantees.

Implementation Options

1. Conservative: merge the docs-only PR as-is after confirming wording and paths are accurate.
2. Balanced: merge the docs note, then open a follow-up issue to add a runtime warning when $HOME/cronjob.toml exists but $HOME/.openab/cronjob.toml does not.
3. Ambitious: add automatic migration or backward-compatible discovery for one release window, with clear logs and tests around old/new path behavior.

Comparison Table

Recommendation

Advance the docs-only PR as the immediate fix, because it is low-risk and directly improves upgrade procedure quality. For merge discussion, pair it with a follow-up issue for a scheduler warning when the old path exists. Automatic migration can be considered later, but it should be split from this PR because it changes runtime behavior and needs tests.